Linking objects to SOAP Web Services

You can use functions provided by external web services in your system by adding a SOAP Web Service behaviour to an object using Object Designer. You can then map the input and output parameters used by a web service method to the appropriate attributes.

To add the SOAP Web Service behaviour to an object:

1. Open the object that you want to use the SOAP web service with in Object Designer.
2. Create the string attributes that you need to map to the parameters in the web service.
3. Select the object at the top of the Attributes tree, then in the Properties grid, click alongside Behaviours.
   The Behaviour Selection dialog appears.
4. Select SOAP Web Service in the Available Items list, then click .
   Web Service moves to the Selected Items list.
5. Click OK.
   The Behaviour Selection dialog closes, and a new item, Web Services, appears in the Property grid.
6. In the Properties grid, click alongside Web Services.
   The SOAP Web Services dialog appears.
   
7. Select the Creation, Update, or Deletion tab depending on whether you want to call the web service when you create, update, or delete an instance of the business object.
8. In the Authentication Type list, select the type of authentication required by the Web Site that is hosting the web service: None, Windows, or Basic.
9. Type the URL to the web service that you want to use in the SOAP Web Service Description Address box, then click Go.
   The Methods list updates to show the methods contained in the selected web service.

You must select the correct Authentication Type before clicking Go. If the URL to the web service that you want to use includes a query string such as ?wsdl, you must include it in the SOAP Web Service Description Address.

10. In the Methods list, select the method that you want to use.
    The Parameters list updates to show the parameters that the method uses. You now need to map these parameters to the appropriate attributes.
11. Drag each of the Parameters that you want to use onto the appropriate Service Desk or Asset Manager Business Attributes, then click OK.
12. Save the changes to the business object.
    Three new attributes are automatically added to the object to store the web service creation, update, and deletion status. These attributes record the returned values of the web service and are useful for capturing any error messages that are returned.

Linking to Ivanti Process Manager using a web service

You can use the Web Service behaviour described above to call an Ivanti Process Manager (LPM) web service listener. This provides a more efficient way for Service Desk or Asset Manager to communicate with LPM.

An example LPM web service XML file (LPMWSSample.xml) is installed in the Console folder of your Service Desk or Asset Manager installation. You use this XML file to map Service Desk or Asset Manager attributes to LPM payload parameters, which are then used to control the LPM process.

Before you start, you need to create an LPM web service listener using LPMWSSample.xml. See the LPM documentation for information on how to do this.

To map attributes to LPM payload parameters:

1. Add the SOAP Web Service behaviour to the required object, and then set the SOAP Web Service Description Address to the LPM web service for your system, using the appropriate Authentication Type.

The SOAP Web Service Description Address for the LPM web service typically ends with webservicelistener.asmx?wsdl.

2. Click Go.
   The Methods list updates to show the method contained in WebServiceListener.
3. In the Methods list, click ProcessExternalMessage under WebServiceListener.
   The Parameters list updates to show the ProcessExternalMessage parameters.
4. Map the connectorName parameter to the attribute that contains the name of the web service listener that you want to use in LPM.
   You can either populate this attribute automatically using a default value, calculation, or an automatic action instance data value, or your users will need to enter this value on the corresponding Service Desk or Asset Manager window.
5. Right-click the fieldContext parameter, then click Load LPM Template on the shortcut menu.
   The Open dialog appears.
6. Browse to, then open LPMWSSample.xml from the Console folder.
   The field contexts for the LPM parameters are loaded.
   
7. Map as many of the items under fieldContext that are named parameter## to Service Desk or Asset Manager attributes as you need, then click OK and save the changes to the object.
   The parameter values that you map are those that are sent to LPM, and which are then used in LPM as part of your LPM process. For more information about designing processes in LPM, see the documentation supplied with LPM.

You cannot map ModuleName, ModuleGuid, ClassName, ClassGuid, ObjectGuid, or ProcessGuid from the Parameters list – these are used internally.

You can map the top-level fieldContext parameter to a Service Desk or Asset Manager attribute. This parameter contains the xml payload that is generated from all of the field contexts that you map, and which is then sent to LPM. You might find this useful for debugging.

The ReturnParameter returns True or False, depending on whether or not the communication to LPM is successful.

You can use the SOAP Web Service diagnostic logging category in the Framework and Web Access applications in Configuration Centre to log information about when the web service behaviour is used. This category logs the web service URL called, the parameters passed to the web service, the return values and return status from the web service, the time to execute the web service, and the authentication parameters passed to the web service. For more information about configuring diagnostic logging, see Diagnostic logging.